home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / time / sunclock / sunclock.doc < prev    next >
Encoding:
Text File  |  1992-08-03  |  5.2 KB  |  109 lines
  1. SunClock - Amiga Version 1.0 
  2.  
  3. Amiga Version by Mark Waggoner, <waggoner@ichips.intel.com> based on an 
  4. X11 version by John Mackin,  <john@cs.su.oz.AU>, based on a Suntools 
  5. program by John Walker,  <kelvin@acad.uu.NET>. 
  6.  
  7. OVERVIEW: 
  8.      This program is a clock that shows which portion of the Earth's 
  9.      surface is illuminated by the Sun.  It is designed to be usually 
  10.      iconic (a window on the workbench screen), but can be opened for a 
  11.      larger display with the time updated every second and both the local 
  12.      timezone and UTC displayed. 
  13.  
  14. OPTIONS and TOOLTYPES: 
  15.      The CLI options and the tooltypes are the same.  They are: 
  16.      LEFT=n    Set the X coordinate of the workbench window. 
  17.                   Example: LEFT=100 
  18.      TOP=n    Set the Y coordinate of the workbench window. 
  19.                   Example: TOP=10 
  20.      DONOTADJUST    Normally, if you start SunClock with a workbench that is 
  21.                   not interlaced, it will halve the height of the map 
  22.                   image by displaying only every other line.  If you don't 
  23.                   want it to do this, add a DONOTADJUST tooltype or 
  24.                   option.  Note that under 1.3, the tooltype needs to be 
  25.                   DONOTADJUST= 
  26.      FULLSCREEN    Start the program with the full screen image rather than 
  27.                   the workbench window.  Under 1.3, the tooltype needs to 
  28.                   be FULLSCREEN= 
  29.      
  30.      Tooltypes and CLI options MUST be in uppercase.  An example of 
  31.      starting sunclock from the CLI is: 
  32.      SunClock TOP=10 LEFT=300 DONOTADJUST 
  33.      
  34. OPERATION: 
  35.      There are only three things you can do with SunClock.  Switch between 
  36.      the "iconized" workbench window and a full screen display, bring up 
  37.      the "About" window, and quit.  Switching from the workbench window to 
  38.      the full screen display is accomplished by selecting the "Iconize" 
  39.      project menu or by double clicking on the image.  Double clicking on 
  40.      the workbench window will switch you to a full screen display, while 
  41.      double clicking on the full screen display will switch you back to 
  42.      the workbench window. 
  43.      
  44.      The "About" project menu will open a window with a brief synopsis of 
  45.      the program options.  You may quit the program entirely by clicking 
  46.      on the close window gadget of the workbench window or selecting the 
  47.      "Quit" project menu. 
  48.      
  49. WHAT TIME IS IT? 
  50.      In order for SunClock to correctly calculate the illuminated portion 
  51.      of the globe, it must know what time zone you are in and how far away 
  52.      from GMT (Greenwich Mean Time) you are.  This is accomplished by 
  53.      reading the environment variable TZ.  The value that this should take 
  54.      is as follows: 
  55.         ZZZnDDD 
  56.      where: ZZZ = your time zone name (e.g. PST) 
  57.               n = the number of hours you are away from GMT. 
  58.             DDD = your time zone name during daylight savings. 
  59.      For the west coast of the United States, this would be accomplished 
  60.      with the command: 
  61.         Setenv TZ PST8PDT 
  62.      
  63.      This format is determined by the Aztec C library function gmtime(). 
  64.      If you do not set this environment variable, SunClock will assume 
  65.      that the time it retrieves from the system is GMT and, unless you 
  66.      live in England, you will get an incorrect view of the world.  Note 
  67.      that Aztec's time functions don't actually do anything with the 
  68.      daylight savings time zone name, so it is not actually necessary.  If 
  69.      you want the time zone to be correct during daylight savings time, 
  70.      you will need to change the value of the TZ environment variable. 
  71.      For the Pacific time zone, for example, you would need: 
  72.         setenv TZ PDT8 
  73.  
  74. BUGS: 
  75.      The illuminated area shown is the area which would be sunlit if the 
  76.      Earth  had no atmosphere.  The actual illuminated area is larger 
  77.      because of  atmospheric refraction and twilight. 
  78.      
  79.      You will get an incorrect view if the environment variable TZ has not 
  80.      been set or is incorrectly set.  See above. 
  81.      
  82.      The program has been tested on Amiga OS V2.04 and 1.3.  If you find 
  83.      bugs, please report them to me (Mark Waggoner).  The program was 
  84.      developed with Aztec C V5.0a, and completed with V5.2a to make the 
  85.      environment variables compatable with the standard Amiga environment 
  86.      variables.  I do not know if it will compile with SAS. 
  87.  
  88. OTHER CREDITS: 
  89.      The X11 version was posted in comp.sources.x Volume 9, Issue 62. The 
  90.      original Suntools program was posted in comp.sources.sun  Volume 1, 
  91.      Issue 79. 
  92.      
  93.      This program is public domain and may be freely copied as long as the 
  94.      notices at the top of Main.c remain intact.  (I suppose "public 
  95.      domain" and restrictions are contradictory, but I'm going with what 
  96.      the previous versions of the program required.) 
  97.      
  98. BACKGROUND: 
  99.      SunClock calculates the position of the Sun using the algorithm in 
  100.      chapter 18 of: 
  101.         "Astronomical Formulae for Calculators" by Jean Meeus, Third 
  102.         Edition,  Richmond: Willmann-Bell, 1985. 
  103.      and Mercator projects the illuminated area onto map image.  The Sun's 
  104.      position is calculated to better than one arc-second in accuracy. 
  105.   
  106.  
  107.   
  108.  
  109.